home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Tool Chest / Development Kits / MPW etc. / Debuggers / SADE / SADE 1.3.3 / SADE New User WorkSheet next >
Encoding:
Text File  |  1992-06-12  |  12.0 KB  |  252 lines  |  [TEXT/sade]
  1. #    Symbolic Application Debugging Environment    1.3 
  2. #
  3. #    Copyright Apple Computer, Inc. 1987-1992
  4. #    All rights reserved.
  5.  
  6. ###############################################################################
  7. # You may be able to use Sade using only Menu commands.  However, if you are
  8. # doing some things repeatedly, you may save time by learning to write some
  9. # commands, saving them, using them the next time around.
  10. # This worksheet contains some commands you might like to try.
  11. # It also contains a section on how to debug MPW tools, and MacApp code.
  12. #
  13. ###############################################################################
  14. # Execute commands in the Worksheet as in MPW with the Enter key.  With a command
  15. selected, you can also click on the status box in the upper left hand corner;
  16. which has identical effect.
  17.  
  18. Version      # To display SADE's version information; or use About SADE in Apple menu.
  19.  
  20. Help        # Get a list of help topics; or use SADE Help menu command in Find menu.
  21.  
  22. # When you compile and link your application, specify the -sym on option to create
  23. # the file containing symbol information (.SYM) that SADE requires for debugging. 
  24.  
  25. # Note that the following commands use one of the sample applications that comes
  26. # with the SADE disk. Substitute a different sample application or one of your own
  27. # applications if you wish.
  28.  
  29. # Identify the target application to debug and its symbol file:
  30.     Directory 'SADE:SADE 1.3 Tutorials:CExamples:C Tutorial 1'
  31. #    Sourcepath 'pathname1','pathname2'    # This command is not necessary with Sample1
  32.                                         # because its source is in one directory. Use
  33.                                         # SourcePath only if your source files are in 
  34.                                         # multiple directories or in a different 
  35.                                         # directory than your application.
  36.     Target 'Sample1'    # assumes symbol file is 'Sample1.SYM'
  37.  
  38. # You will see that Target not only identifies the application but launches it, opens
  39. # the source file, and breaks at the first statement of the main program.
  40.  
  41. # Now select a statement of interest; e.g., DoMenuCommand (use the Mark menu), and 
  42. # choose the Go Til command from the SourceCmds menu. SADE sets a temporary 
  43. # breakpoint on DoMenuCommand and resumes operation of Sample1 (the traffic light 
  44. # appears). SADE will be reentered when the breakpoint is encountered; in this case, 
  45. # choose Red Light from the Traffic menu and SADE highlights DoMenuCommand in the 
  46. # source file.
  47.  
  48. # Now choose a variable to watch, e.g., gStopped, which tells whether the light is
  49. # Red (TRUE) or green (FALSE); highlight gStopped here and select Add Watch Variable
  50. # from the Variables menu. SADE opens a window displays its current value. SADE will 
  51. # also show its new value whenever you step. 
  52.  
  53. # Now step the program using Step in the SourceCmds menu. If you want to step into a
  54. # routine use the Step Into menu command. For example, after 4 or 5 steps you can 
  55. # step into the SetLight routine when SetLight (FrontWindow(), false); is highlighted.
  56. # Within the SetLight routine, gStopped should change to 0. 
  57.  
  58. # To remove Sample1 as the target, issue this command:
  59.     Kill
  60.  
  61. ###############################################################################
  62. # When your application is running, you can suspend it and enter SADE by 
  63. # pressing <command-option> <SADEKey>.
  64. # The default SADEKey is <numeric-key-pad-period>.
  65. # To change it, modify and execute the following:
  66.  
  67. SADEKey <new key code>
  68.  
  69. # See Inside Macintosh Volume 5, pages 191-192 for the key codes for the various keyboards.
  70.  
  71. ###############################################################################
  72. # Debugging Object Pascal and MacApp
  73.     MacApp methods are supported.  Within methods, references to the instance 
  74.     variables of the object can be made without qualifying those references by SELF.
  75.     These free references to instance variables can also be done in C++ member 
  76.     functions.
  77.     
  78.     A SADE variable, BreakIfNoSource, defaults to 0. When 0, a Step Into will 
  79.     continue stepping until there is source statement information available for the 
  80.     instruction at the program counter. Stepping into a method call will break 
  81.     at the first instruction of the method. The down side is that if SADE steps into 
  82.     something without statement information, it will appear SADE has hung.  It hasn't, 
  83.     it's just very busy executing your code 2 to 3 orders of magnitude slower than 
  84.     normal.  This down side should only affect you if you step into code which has
  85.     been built without symbols.  Should you do so, you have a choice of waiting for 
  86.     completion of stepping or rebooting.  Setting BreakIfNoSource to 1 will make 
  87.     SADE break when no source information is available for the PC.
  88.     
  89.     To step into a method use the Step Into menu item from the SourceCmds menu 
  90.     (Source vs Asm checked in SourceCmds) or the Step Line Into command and options.
  91.     To avoid stepping through MacApp's method dispatch code, you should assemble
  92.     MacApp's ≈.a files with "-SYM OFF".  Also, UObject.p.o and UMacAppUtilities.p.o
  93.     should be compiled with "-SYM OFF" because routines in these files are called as
  94.     part of the method dispatch.
  95.     
  96.     Follow these simple steps when debugging MacApp code with SADE.  Assume the
  97.     target is the MacApp sample program DemoDialogs:
  98.     
  99.     (1)    In MPW, set the directory to the location of your sourcefiles and build your 
  100.     application with symbol information:
  101.             directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:"
  102.             mabuild -sym -autobuild DemoDialogs
  103.     The -autobuild option will build the MacApp libraries if necessary.
  104.     
  105.     (2) Double click on the DemoDialogs.sym file from the Finder.  The file should
  106.     be located in the newly created .NoDebug Sym folder within the sources folder.
  107.     This will launch SADE, set the directory and sourcepath and target DemoDialogs.
  108.     However, SADE still does not know where the MacApp libraries are located and so
  109.     you will be prompted to locate them if you attempt to step into a MacApp method
  110.     or suspend execution in a MacApp method.
  111.     
  112.     You may wish to launch SADE and setup the directory and sourcepath variables
  113.     yourself before targeting DemoDialogs. To do so, execute the following commands
  114.     from SADE:
  115.         directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:.NoDebug Sym:"
  116.         Sourcepath    "hd:MacApp® 2.0.1:Examples:DemoDialogs:", ∂
  117.                     "hd:MacApp® 2.0.1:Libraries:"
  118.         Target 'DemoDialogs'
  119.         
  120.     The file MDemoDialogs.cp should now be open and the program counter should be at
  121.     the first statement: void main ()
  122.         
  123.  
  124. ###############################################################################
  125. # Low-level Debugging
  126. # You can set SourceCmds menu to Asm Debugging.
  127. # If you use Step menu command now, SADE executes one instruction at a time rather 
  128. # than one source statement at a time.
  129.  
  130. # Here are some commands you can use for low-level debugging:
  131.     Stack                        # Show the address of, owner, and caller of all 
  132.                                 # stack frames
  133.  
  134.     Disasm pc 10                # Disassemble 10 instructions starting from the pc
  135.     
  136.     Disasm myProc.(1)             # Disassemble 20 (the default) instructions starting
  137.                                 # from the first statement of procedure myProc
  138.  
  139.     Dump a0 64                    # Display 64 bytes beginning at location pointed to
  140.                                 # by register a0
  141.     
  142.  
  143. # Macintosh System Structures
  144.  
  145.     heap                        # Display the heap pointed at by theZone
  146.     heap check                    # Validate the heap pointed at by theZone
  147.     resource                       # displays all open resource maps in target application
  148.  
  149.     windowList^                    # Display FrontWindow as a grafPort
  150.     ^WindowRecord(windowList)^    # Display FrontWindow as a windowRecord
  151.     *(WindowRecord *)(windowList)    # doing the same with a C expression
  152.  
  153. ###############################################################################
  154. # Source Level Debugging (Set SourceCmds to Source Debugging)
  155. # If you use Step menu command, SADE steps one source statement at a time. Here is
  156. # a procedure for stepping a given number of times; note the use of the onEntry 
  157. # keyword, which tells SADE what to do after each step; in this case, take another 
  158. # step.
  159. define StepCount
  160. proc __Step__
  161.     if (StepCount > 0)
  162.         StepCount := StepCount - 1;
  163.         step onentry __step__
  164.     end
  165. end
  166. proc StepN(__n__)
  167.     StepCount := __n__
  168.     Step OnEntry __Step__
  169. end
  170.  
  171. StepN (3)    # Step three times
  172.  
  173. #  After you're finished, you may wish to undefine StepCount.
  174. undefine StepCount
  175.  
  176.  
  177. ###############################################################################
  178. # To debug an MPW tool (using the example tool Count), compile and link the tool 
  179. # with symbolic information (-sym on|full). Be sure to specify the file type and 
  180. # creator when you Link an MPW tool:
  181.     Link -t 'MPST' -c 'MPS ' -sym on
  182.             
  183. # From the Finder, double-click on the tool's SYM file. This will launch SADE, set the
  184. # directory and target the tool. As long as MPW is still running, SADE will make MPW
  185. # the frontmost application. Otherwise, SADE will prompt you to locate the MPW Shell 
  186. # and then it will launch MPW. You may then run your tool from MPW and SADE will 
  187. # execute it, stopping at the first line of the main program.
  188.  
  189. # Another way of targeting a tool would be to execute the following commands from 
  190. # SADE to set the directory and target the tool.  After MPW is launched, run the tool.
  191.  
  192.     Directory "hd:mpw:Examples:CExamples:"
  193.     Target "hd:mpw:mpw shell" using "Count.SYM"
  194.     
  195. # To remove the tool as the target, kill the tool using either the Kill menu
  196. # command (which calls KillTool) or issue KillTool from the SADE worksheet. 
  197. # Do not issue the Kill command from the worksheet.  This will kill MPW.
  198. # KillTool will shutdown the tool and leave MPW running, so you can continue to 
  199. # work in MPW if you wish. 
  200.     KillTool
  201.  
  202.  
  203. ###############################################################################
  204. # The folder 'SADE Example Scripts' contains files with examples of the SADE language.
  205. # You might find these interesting if you are attempting to write your own scripts.
  206. # To execute these scripts, you must first target an application.  Then set the  
  207. # directory to the folder containing the scripts.
  208.  
  209. Directory concat (SADEDir,'SADE Example Scripts:')    # SADEDir is defined in SADEStartup
  210.  
  211. # Then select any line beginning with 'execute' and press Enter; commands nested
  212. # under the execute line represent procedures defined in the script files and
  213. # can then be run as well.
  214.  
  215. Execute 'MiscProcs'
  216.     DisplayFCBs                # Displays information about all open files
  217.     displaywindowlist        # Displays the name of each open window in the target application.
  218.     InterList('routine name', 'output filename')    # interleaves statements and associated instructions
  219.     factorial (20)            # Evaluate the factorial of 20 and printout the results
  220.  
  221. Execute 'Resource'
  222.     ResMap "CODE"            # Display information about all CODE resources.
  223.     ResMap                    # SLOWLY mimics the resource command
  224.     ResVerify                # mimics the resource check command
  225.  
  226. Execute 'sc7'
  227.     StackCrawl7                # Display a possible calling chain sequence.  There is
  228.                             # also a macro 'sc7' defined in the script which executes
  229.                             # stackcrawl7.
  230.     
  231.  
  232. ###############################################################################
  233. # Command Key Equivalents: The AddMenu command allows you to add new menus to the
  234. # SADE menu bar. You can optionally add a key equivalent for any of the menus you
  235. # create by preceding the key with a frontslash. Since the SourceCmds and Variables
  236. # menus are both defined in the file SADEStartup, you can change the key equivalents  
  237. # for the commands defined in those menus if you wish. 
  238.  
  239. # For instance, the key equivalent for Show Dereferenced Value is Command-◊, or 
  240. # Command-Option-Shift-V. If you find this a difficult key combination to press, you 
  241. # may change it by replacing '◊' with a different character. The best place to make
  242. # this change is in a SADEUserStartup•≈ file that you create. Since any such file will
  243. # be executed after SADEStartup when SADE is launched, your changes will overwrite the 
  244. # same command defined in SADEStartup, but will leave SADEStartup untouched.
  245.  
  246. # Show Dereferenced Value as defined in SADEStartup:
  247. addmenu 'Variables'  'Show Dereferenced Value /◊'    'ShowDereferencedValue(selection(ActiveWindow))'
  248.             
  249. # Create a file SADEUserStartup•MyName and add this line to change the key equivalent only.
  250. # This example changes the key equivalent to Command-9.
  251. addmenu 'Variables'  'Show Dereferenced Value /9'    'ShowDereferencedValue(selection(ActiveWindow))'
  252.